OPC Studio User's Guide and Reference
DAQuality Format Strings
OPC Data Access qualities (instances of DAQuality) can be formatted using standard or custom format strings.
Standard and custom format strings are supported by some overloads of the ToString method. For example, you can supply a format string to the ToString(String) and ToString(String, IFormatProvider) methods. Standard and custom format strings are also supported by the .NET Framework composite formatting feature, which is used by some Write and WriteLine methods of the Console and StreamWriter classes, the String.Format method, and the StringBuilder.AppendFormat method. The composite format feature allows you to include the string representation of multiple data items in a single string, to specify field width, and to align values in a field.A standard DAQuality format string has a form of a single alphabetic character called the format specifier. Any DAQuality format string that is not a standard format string is interpreted as a custom DAQuality format string. This includes strings that contain any whitespace before or after the standard format specifier.
The following table describes the standard format strings and displays sample output produced by each format specifier.
| Format specifier | Name | Description | Example(s) |
| “f” | Full (short) | Includes the QualityChoiceBitField, StatusBitField and LimitBitField symbolic names, but not a NumericalValue of the quality. | Bad BadNonspecific LimitOk |
| “F” | Full (long) | Includes the QualityChoiceBitField, StatusBitField and LimitBitField symbolic names, and a NumericalValue of the quality. | Bad BadNonspecific LimitOk (0) |
| “g” | General (short) | Contains the minimum symbolic names needed to identify the quality; does not contain the numerical value. | GoodNonspecific GoodNonspecific LimitHigh |
| “G” | General (long) | Contains the minimum symbolic names needed to identify the quality, and its numerical value. | GoodNonspecific (192) GoodNonspecific LimitHigh (194) |
You can create a custom DAQuality format string, which consists of one or more custom format specifiers, to define how to format the DAQuality. A custom DAQuality format string is any format string that is not a standard DAQuality format string.
The following table describes the custom format specifiers and displays sample output produced by some of the format specifiers.
| Format specifier | Name | Description | Example(s) |
| C C(format) |
QualityChoiceBitField | Value of the named property, optionally formatted with format. | Good |
| Cn Cn(format) |
Numerical value of QualityChoiceBitField | Numerical value of the named property, optionally formatted with format. | |
| Ib | IsBad | Value of the named property. | False |
| Ig | IsGood | Value of the named property. | True |
| Iu | IsUncertain | Value of the named property. | False |
| L L(format) |
LimitBitField | Value of the named property, optionally formatted with format. | LimitLow |
| Ln Ln(format) |
Numerical value of LimitBitField | Numerical value of the named property, optionally formatted with format. | |
| N N(format) |
NumericalValue | Value of the named property, optionally formatted with format. | 192 |
| S S(format) |
StatusBitField | Value of the named property, optionally formatted with format. | SensorFailure GoodNonSpecific |
| Sn Sn(format) |
Numerical value of StatusBitField | Numerical value of the named property, optionally formatted with format. | |
| Z Z(format) |
StatusInfo | Value of the named property, optionally formatted with format. | Warning |
| \ | Escape character | Causes the next character to be interpreted as a literal rather than as a custom format specifier. | |
| 'string' "string" |
Literal string delimiter | Indicates that the enclosed characters should be copied to the result string unchanged. | |
| ; | Section separator | Defines sections with separate format. | |
| Other | All other characters | The character is copied to the result string unchanged. |
For example, the format string “S, 0xN(X)” specified that the formatting results should contain the value of the StatusBitField, followed by “, 0x”, and a numerical value of the quality, formatted as hexadecimal number.
| Example Code (C#) | Result |
| new DAQuality(DAQualities.GoodNonspecific).ToString("S, 0xN(X)") | GoodNonspecific, 0xC0 |
| String.Format("{0:S, 0xN(X)}", newDAQuality(DAQualities.GoodNonspecific)) | GoodNonspecific, 0xC0 |
| String.Format("{0:'Quality is 'C}", newDAQuality(DAQualities.GoodNonspecific)) | Quality is Good |
The semicolon (;) is a conditional format specifier that applies different formatting to a value depending on the condition(s) it fulfills. To produce this behavior, a custom format string can contain up to two or more separated by semicolons. These sections are described in the following table.
| Number of sections | Description |
| 1 | The format string applies to all values. |
| 2 | If the quality is Bad, section #2 applies. Otherwise, section #1 applies. |
| 3 | If the quality is Bad, section #3 applies. Otherwise, if the quality is not Good (is Uncertain), section #2 applies. Otherwise, section #1 applies (the Quality is Good). |
| 4 | If the quality is Bad, section #4 applies. Otherwise, if the quality is not Good (is Uncertain), section #3 applies. Otherwise (the quality is Good), if the status is not GoodNonspecific, section #2 applies. Otherwise, section #1 applies (the status is GoodNonspecific). |
| 5 | If the quality is Bad, section #5 applies. Otherwise, if the quality is not Good (is Uncertain), section #4 applies. Otherwise (the quality is Good), if the status is not GoodNonspecific, section #3 applies. Otherwise (the status is GoodNonspecific), if the limit is not LimitOk, section #2 applies. Otherwise (the status is GoodNonSpecific and the limit is LimitOk), section #1 applies. |
| >= 6 | Last 5 sections are taken as if there were just 5 sections. The preceding sections are ignored. |
The sections are ordered in such a way that the rightmost section always represents the worst quality, and the sections to its left represent progressively improving qualities.
For example, the format string “OK;ERROR N” specifies that bad qualities should be formatted as “ERROR “ followed by a numerical value of the quality, while good qualities should simply be formatted as “OK”.
| Example Code (C#) | Result |
| new DAQuality(DAQualities.CommFailure).ToString("OK;ERROR N") | ERROR 24 |
| new DAQuality(DAQualities.GoodNonspecific).ToString("OK;ERROR N") | OK |
| String.Format("{0:OK;ERROR N}", new DAQuality(DAQualities.CommFailure) | ERROR 24 |
| String.Format("{0:OK;ERROR N}", new DAQuality(DAQualities.GoodNonspecific) | OK |